home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Turnbull China Bikeride
/
Turnbull China Bikeride - Disc 2.iso
/
STUTTGART
/
LANG
/
C
/
LIB
/
DESK
/
CORE
/
Desk
/
h_doc
/
Template
< prev
next >
Wrap
Text File
|
1996-05-21
|
8KB
|
217 lines
/*
#### # # # #
# # # # # The FreeWare C library for
# # ## ### # # # # ### RISC OS machines
# # # # # # # # # # # ___________________________________
# # #### ### ## # # # #
# # # # # # # # # # Please refer to the accompanying
#### ### #### # # ##### # ### documentation for conditions of use
________________________________________________________________________
File: Template.h
Author: Copyright © 1992, 1993, 1994 John Winters and Jason Williams
Version: 1.05 (Dec 1994)
Purpose: Loading, caching, and retrieval of window templates
*/
#ifndef __Desk_Template_h
#define __Desk_Template_h
#ifdef __cplusplus
extern "C" {
#endif
#ifndef __Desk_Sprite_h
#include "Desk.Sprite.h"
#endif
#ifndef __Desk_LinkList_h
#include "Desk.LinkList.h"
#endif
extern void Desk_Template_Initialise(void);
/*
* Initialises the Template manager ready for use
* Make sure you call this function before any other Desk_Template_ calls
* --- In future, this call will be extended to include setting up
* the things necessary to use outline fonts in your windows.
*/
extern Desk_window_block *Desk_Template_Find(const char *name);
/*
* Tries to find the named template, and return a pointer to it's
* base Desk_window_block. This is so that you can alter the template
* original. Note that this *is* the original, so don't stuff it up!
* If you wish to USE the template, please use Template Clone!
*/
extern Desk_window_block *Desk_Template_Clone(const char *name, int maxtitlesize);
/*
* Makes a copy of the named template, and returns a pointer to the copy.
*
* "maxtitlesize" is the number of bytes that should be allocated
* for the title - this should be big enough to accomodate ANY title
* string you expect to give to this window. This is because the only way
* to alter the size of this indirected field is to re-create the window
* which is usually an undesirable thing to do. (See below for a list of
* the possible values for this argument)
*
* A value of 0 for maxtitlesize will use the default value (currently 260)
* If the window's title icon is not indirected, this value is ignored
* (so most of the time, using 0 is a sensible thing to do)
*
* Returns NULL if the template can't be found
* Dies with an error if a serious error occurs (malloc failure, etc.)
*
* When you're finished with the clone, use Desk_Template_Free to release
* the memory it is using.
*/
/* NOTE
* The following values may be used for 'maxtitlesize':
* TITLEDEFAULT 0 reserves 260 bytes, enough for a full pathname
* TITLEMIN -1 reserves the title as much room as set in the
* template file (title indirected data size)
* (the recommended value - especially for windows
* with constant title strings)
* (any positive value) reserves 'maxtitlesize' bytes of storage for
* the indirected title data
*/
#define Desk_template_TITLEDEFAULT (0)
#define Desk_template_TITLEMIN (-1)
extern void Desk_Template_Free(Desk_window_block **windowdef);
/*
* Frees up the memory used by a Desk_Template_Clone'd template.
* If you try to Free a non-Clone'd template, it WILL blow up, so don't.
*
* Pass in a pointer to a (Desk_window_block *). The window definition's
* memory (including indirected title/icons) will be freed, and the
* (Desk_window_block *) will be set to NULL to ensure you don't try to use
* it now that it is invalid.
*/
extern void Desk_Template_Delete(const char *name);
/*
* Deletes the named template from the list of available templates, freeing
* any memory claimed by the template. This will "pull the rug out from
* under" any windows created using this template, and your program will
* crash if any such windows are open.
* However, any windows created using Desk_Template_Clone'd templates will
* be unaffected. (Moral of the story: Always use Clone)
* Pass in the identifier string of the template you swish to delete
*/
extern void Desk_Template_ClearAll(void);
/*
* Clears ALL currently held templates. (equivalent to you calling
* Desk_Template_Delete() for each template in turn)
*
* Also releases all fonts that were in use by the loaded templates.
*/
extern void Desk_Template_LoadFile(const char *leafname);
/*
* Loads all template definitions from the specified file.
* Due to the essential nature of templates, if any errors occur, this
* reports to Desk_Error_ReportFatal(Internal)
* After loading a template file, use Desk_Template_Clone to get a copy
* of any of the templates for use.
*
* Loading a second file will simply ADD the new templates to the template
* list. So long as there are no name clashes, you can then use any
* template from either file.
*
* Use Desk_Template_Delete/ClearAll if you don't want to keep old templates
* when loading in new ones.
*
* If you want to use outline fonts in windows, then remember to call
* Desk_Template_UseOutlineFonts() BEFORE you call Desk_Template_LoadFile() (see below)
*/
extern void Desk_Template_UseOutlineFonts(void);
/*
* Call this BEFORE calling Desk_Template_LoadFile() if you wish to use outline
* fonts (rather than the system font) in your windows. It allocates the
* font usage array, and also adds an atexit handler to lose all the fonts
* you are using when your program exits.
*
* NOTE that future versions of RISC OS *WILL* supply an outline font as the
* system font, so your program should offer a choice of system font OR
* outline font to the user.
*/
extern void Desk_Template_UseSpriteArea(Desk_sprite_area area);
/*
* This can be called before any Desk_Template_Find or Clone call to set the
* sprite area that will be used by all future Find/Clone'd templates.
* Set this to NULL (the default if you don't call this function) in order
* to use the WIMP sprite pool.
*/
extern void Desk_Template_LinkSpriteArea(const char *identifier, Desk_sprite_area area);
/*
* Sets the given single window template to use the given sprite area
*/
/*
The rest of this file is not for user consumption - the declarations are
used only by the Desk_Template_ functions and Desk_Window_ModeChange().
Desk_Window_ModeChange() needs to get inside the template data to modify
fonts handles.
*/
/* Could have '#if defined( Desk__making_Window) || defined( Desk__making_Template)' here... */
typedef struct
{
Desk_linklist_header header;
char identifier[Desk_wimp_MAXNAME + 1];
Desk_window_block *windowdef;
int dataoffset;
int templatesize; /* size of window+icons+indirect data */
int indirectsize; /* size of expanded indirect data */
char *indirectdata;
} Desk_template_record;
#ifdef Desk__using_SDLS
extern Desk_linklist_header *Desk_Template__Ref_list( void);
extern Desk_font_array **Desk_Template__Ref_fontarray( void);
#endif
#if defined( Desk__using_SDLS) && !defined( Desk__making_Template)
#define Desk_template_list (*Desk_Template__Ref_list())
#define Desk_template_fontarray (*Desk_Template__Ref_fontarray())
#else
extern Desk_linklist_header Desk_template_list;
extern Desk_font_array *Desk_template_fontarray;
#endif
#ifdef __cplusplus
}
#endif
#endif